Shareware Grab Bag/Shareware Grab Bag.iso/007/cmenu4c.arc/CMENU4.DOC

Text File | 1985-11-06 | 21KB | 439 lines

                            Cmenu4 Documentation
                              Daniel B. Doman
                        132 East 45th Street Apt. 5G
                            New York, N.Y. 10017


    These programs represent considerable time, and effort. I am marketing
them using the FreeWare (tm) marketing approach. In this way I can
distribute reasonably priced software. If you find these programs useful,
or if you plan to implement them in a commercial environment, a payment of
$15.00 is suggested. You are free to copy these programs, and pass them
around, but you may not charge for such distribution, nor may you modify
the Copyright notice that appears on the bottom of the menu. Please let
your conscience be your guide.
    A more powerful "resident" version that is much faster is available by
mail only. It does not use batch files of any kind. Rather, your programs
are executed from within the menu. Program entry, and exit is almost
instantaneous. The speed of the menu is limited only be your system's
ability to load your programs, and the speed with which your monitor can
repaint the menu. The resident version executes roughly 50% faster
Cmenu4C. Because it does not need to write to any drive, you can run it on
a write protected drive. If you are interested in this version please send
a check for $35.
    Cmenu4 was written for distribution by modem. The code was made as
compact as possible. Several features were left out in order to keep code
size down. Larger, more sophisticated versions are available, but they
would not be practical to transmit by modem. Also, for similar reasons,
this documentation is necessarily short. You may write for more detailed
documentation.
    Registered users will be kept up to date on all new versions, and
modifications. In addition, they are eligible for assistance should they
have any problems. I cannot answer support questions unless you register
your copy.

                Please make checks Payable To DannySoft Inc.

Mailing Address:

                           Daniel B. Doman
                           132 East 45th Street Apt. 5G
                           New York, N.Y. 10017

                                  History

    These programs were written as part of a shell for network design. I
wanted to make the networks that I built as easy to use as possible. Also,
certain operations needed to be made in a formal, and structured manner,
and a menu was the best way to do this. The programs were originally
written in Compiled Basic. I rewrote them in C with the expectation of
using the FORK/EXEC functions, however, many network functions require a
complex, and varied series of commands, and the data file would have had
to be excessively complex. This  is the network version, and works with
batch files. It is intended to be easy to use, set up, and speed was a
primary consideration in the design. This version of the Cmenu programs is
a result of many users asking about "nesting menus". While the earlier
version, Cmenu2 could nest menus through the use of the menu batch file,
this version can actually load another data file without having to exit to
DOS. If you are updating from Cmenu2, or Menu2.exe, please read the
changes section. A new field has been added, and some of the "key words"
that the program searches for have been changed for clarity.



                                   Theory

    When the Menu program is loaded, it reads in a file containing the
Selection names, their descriptions, and the commands that they will call.
The menu supports passwords. If a password is put in the data file, the
menu will ask for it. The Cmenu4 program runs inside a batch file. It
dynamically creates a batch file called Runit.bat that contains the
commands for the menu choice that the user selected. Runit will change to
to the appropriate drive, and directory, run your program, return you to
your default drive, and directory, and then call the Menu.bat again. Your
menu batch file must be called MENU, because Runit.bat always calls MENU
when it is finished. One can move around the menu with the cursor keys,
and the END & HOME keys. Once things are set up properly, one merely moves
to the desired selection, hits the RETURN key, and the application is up,
and running. After quitting the application, the MENU batch file is
automatically called again, and back comes the menu. The menu is really
fast. It should load from a hard disk in a little under two seconds. While
it will work on a floppy system, it strikes me as overkill to do so.


                                   Setup

    Run Cmenu4 with the sample data file (Menu.dat) so that you can get an
idea of what it should look like. First run it without the MENU.BAT so
that you can look at the RUNIT.BAT that it creates. The run it using the
MENU.BAT. Below is a sample Menu.Bat

MENU.BAT

Echo Off
C:   <-this may not be necessary, but it is good housekeeping
cd\  <-this may not be necessary, but it is good housekeeping
Cmenu4    {optional menu file name} {switch options}
Runit  <-runit is dynamically created

    note: If you say Cmenu4 %1 %2 %3 %4 %5 %6 , you can type "MENU
    {options}" , and these options will be read in as `replaceable
    parameters'. Read `programming tips' for more details.

    Runit.bat contains all of the necessary commands to run a normal
program. If you program is on another drive, it will change drives. If it
is on another subdirectory, it will change to that subdirectory, and then
call your program. Cmenu4 considers "Home" to be the drive, and directory
in which you load it. It will program runit.bat to return you to that
drive, and subdirectory before calling the Menu.bat again. If you exit to
DOS, and run Cmenu4 on another drive, or directory, "Home" will be on the
new drive, or directory. Home is where you load Cmenu4.
    Below is a typical Runit.bat

RUNIT.BAT

CD C:\LOTUS
123.EXE
C:       <- Cmenu4 always returns you to your home drive
CD\      <- Cmenu4 always returns you to your home directory
MENU

    If your program is on a different drive, Runit.bat will change to that
drive. If you need to run a more complex series of commands to execute
your program, turn to the "Programming Tips" section of this documentation.


                               Switch Options

         Cmenu4 Checks for the display type. It tests your system switch
settings. If you are using a compatible that confuses the program, or a
color card with B&W monitor, you can force the display mode that the
program will run under

         -B   Force the program to Monochrome Mode
         -C   Force the program to color mode

         When Cmenu4 executes a command, it will clear the screen, and say
         EXECUTING xxxxxxx .

         -R   Turns the "Execution" Display Off

  You can exit the menu by pressing the ESC key.

         -E   Disable the ESC Key for exit.

         Cmenu4 looks for a data file named "Menu.dat" . You can tell it
         to look for a data file by any other name.

         Cmenu4 SPECIAL.DAT  <- Tells Cmenu4 to load the data file
                                SPECIAL.DAT

         -V  Gives Version number. Program Quits afterwards.

                           Special Color Switches

    These switches take color values as per your BASIC manual ie..
    0=BLACK, 4=RED etc..

         -BK  Background Color (do not use color value higher than 7)

         -FR  Menu border Color (the menu frame)

         -TI  Color for the time display

         -RE  reverse video foreground color (currently selected choice)

         -LA  color for selection names

         -LO  color for my logo at bottom of menu

         -MT  color for menu title on top

         -DE  color for the selection description (above logo)

 Example: Cmenu4 -fr7 -ti12 <- Sets frame color to White, and time to
             Light Red.

    The options can be given in any order, are NOT case sensitive, and
there is no real limit to the number of options that you can give. You can
specify the subdirectory that contains the data file e.g..
Cmenu4 c:\datafiles\SMART.DAT. If you give the same option twice with two
different values, the second value is accepted. Below is a silly example
that would still work.

Cmenu4 SPECIAL.DAT -B STUPID.DAT -C GREAT.DAT -B SILLY.DAT -C SMART.DAT

    The program will execute the LAST color option, and the last data file
    option given. Cmenu4 would load SMART.DAT in COLOR Mode.

    The above is NOT recommended, but it does show how the switches work.
Except in unusual cases, it should not be necessary to force the colors
with the -C, or -B options. The other color options are for differences in
taste. Unless you plan on nesting your menus, you might as well use the
default menu data file name "MENU.DAT".


                                Menu Styles

    Cmenu4 will arrange your menu in two or three columns, depending on
the number of selections that you have. The menu selections are normally
in two columns, but if the number of selections is Divisible by three (3),
or greater than ten (10), they will be in three columns. You may want to
pad your menu with a semi-useful selection in order to make the columns
even.


                              Newmenu Program

    This program is a simple, and painless way to build you own menu data
file. Although you have the option of putting in a password, it is not
recommended that you do so the first time. In any case, if this menu is to
be used on your own personal system, passwords would be silly. Perhaps
this reflects my own tastes, but the Newmenu program will capitalize all
menu selection names, commands, and passwords. It will capitalize the
FIRST letter of each word in your descriptions. If you have your CAPS lock
key toggled on, everything will be capitalized. The prompts that this
program gives are discussed below. As an aid in designing symmetrical
menus, the Newmenu program will tell you on the bottom of the screen
whether the menu would be ragged, or even and the number of columns at THE
CURRENT selection position. The Newmenu program will automatically insert
the appropriate "Exit" commands. It will also take care of the commands to
switch to the Submenu. You do not need to put these commands in yourself.

MENU TITLE?   <- This is the name that will appear in the box at the top
                 of the menu

SELECTION?    <- This is the selection name that is put on the menu. Press
              RETURN if you do not want any more selections.

DESCRIPTION? <- A description of what the selection does

SUBDIRECTORY? <- The drive, and subdirectory of your program goes here.
              You must use the form - "C:\LOTUS". DO NOT omit the drive
              letter. If you leave this field blank. Your program will be
              executed on the default drive, and subdirectory

COMMAND?      <- The name of the program, or DOS command that you want to
              execute. It can be a program such as CHKDSK.COM, or it can
              be another batch file. If you call another batch file,
              remember to make the last line MENU, so that you will call
              up your menu again.

PASSWORD?     <- If you just hit the RETURN KEY, there is no password. DO
              NOT ADD SPACES. They count as part of the password. Two
              spaces followed by a return means that the password is two
              spaces!! The menu title has a password for exit functions.
              You can prevent an exit unless the user has the correct
              password. If you elected not to have passwords, you will
              not see this prompt.

    When you are done, just hit the return key for selection name. You
will be asked if you want to accept the default submenu. The default is a
collection of useful DOS commands, and the submenu title is UTILITY MENU.
You can build your own, or accept the default. Hit the RETURN KEY to
accept the default. You will then be asked if you want to omit the submenu
entirely. This option is primarily intended for nested menus.

                              Newmenu Options

    Newmenu will build a menu data file called "Menu.dat", but if you
enter "NEWMENU SPECIAL.DAT". It will create a data file by that name. If
you already have a data file by the same name, it will rename that file
with an .OLD extension. By the way, the .DAT extension is not necessary,
but a nice convention. Although it you will probably never need to, you
can specify the drive, and directory in which you want to create the data
file e.g.. NEWMENU C:\DATA\SAMPLE.DAT.

    All of the color options will also work with Newmenu.

                              Programming Tips

                          Menu Data File Structure

    I purposely designed the Cmenu4 programs to use ASCII data files in
order to let people modify them with any text editor. Do not modify the
data file until you understand how Cmenu4 works
    The menu data file contains four, or five fields, separated by COMMAS
(,). Do not use a comma in any Name, Description, Or Command. The fifth
field is the password. Anything after a FOURTH Comma (if there is one),
INCLUDING SPACES will be interpreted as a password.
    The structure is as follows:

SELECTION NAME,DESCRIPTION,DRIVE & DIRECTORY,COMMAND,PASSWORD (If any)

    Any field can be blank.

    The First line of the data file is the menu title, it will have two or
more commas following it, or it may (for clarity) have ,NUL,NUL following
it. A FOURTH COMMA, followed by ANYTHING will be the password to exit the
menu. If you leave the directory field blank, the program will be executed
in the default drive, and directory. If you leave the command blank, this
will be interpreted as a command to exit. There is a maximum of 21
selections per menu screen, including the Exit, and Submenu options.

SAMPLE MENU,,        <-No Password Here
SAMPLE MENU,,,,SECRET <-Password=SECRET

CHKDSK,Do A CHKDSK On Drive C,,CHKDSK C:/F/V <-No password Here
ACCOUNTING,Accounting Programs,C:\JEWEL,JEWEL,SECRET <-Password="SECRET"

    About half way down the data file you will see a name followed by a
comma, and the word SUBMENU in the description field. That tells the
Cmenu4 program that this is the beginning of the submenu. The word SUBMENU
MUST be in CAPS. Everything following the submenu title will be the
selections for the submenu. The last line will be a command to return to
the main menu. The program looks for the command "SWAP" as the key word to
swap between the primary, and secondary screens.

UTILITY MENU,SUBMENU,, <-Submenu Title

RETURN TO MAIN MENU,,,SWAP  <-If command=SWAP, Menu knows that this is
                            command to switch between the Main, and
                            Submenus.

    If the command is "DOS", or if there is NOTHING for a command, the
menu interprets this to mean "EXIT TO DOS"

EXIT TO DOS,Leave Menu System,,DOS <- command is to leave menu.
EXIT TO DOS,Leave Menu System,,    <- command is to leave menu.

    If you delete all of the lines that say EXIT TO DOS, the only way out
of the menu is by pressing the escape key. If you also disable the escape
key with the -E option, there is no way out.

                               Field Lengths

    NAME                    <- 30 Characters. Because this field is for
                            both Title & Selection name, you should
                            consider your maximum Selection Name length
                            to be 20 Characters

    DESCRIPTION             <- 55 Characters
    DIRECTORY               <- 65 Characters
    COMMAND                 <- 50 Characters
    PASSWORD                <- 8 Characters

    If you exceed the maximum field length for a field, the program will
start reading into the next field. This can cause unexpected results.


                             Special Functions

                                   Pauses

    As soon as a command is finished, the menu is reloaded. This can be
inconvenient if the command is one like "DIR /W". You can direct the menu
to add a pause before reloading the menu by adding the characters "(P)" to
the command.

DIR A:,Directory Of Drive A,A:\,DIR /W(P)      Adds Pause before reload

                                Nested Menus

    If you want to `nest' your menus, you can give the program a command
to load a new data file without actually exiting the program. Put the in
your command field the words "(NEST)" followed by the new data file you
want to load. The program will see the key phrase (NEST), and know that it
should read in a new data file. The menu remembers the data file it first
loaded. If you have the command (NEST) without any data file, the program
will read in the data file that it started up with. The new data file
should load in about one second. You can nest this way as many times as
you want. Below are some examples.

FRED MENU,Load The Fred Menu,,(NEST)FRED.DAT   <- Program loads FRED.DAT
                                               data file

MAIN MENU,Return To Regular Menu,,(NEST)       <- Program reloads Original
                                               menu data file.

    If you want to change colors between menus, or change one of the other
command line options, you will have to restart the menu. You can do this
as a menu selection using the following.

MENU.BAT

echo off
cd\
Cmenu4 %1 %2 %3 %4 %5 %6 %7 %8 %9
Runit.bat

    A menu command such as "MENU DATABASE.DAT -E" will reload the menu
with the DATABASE.DAT data file, and the ESC (escape) key disabled. After
you execute a command from that menu (or quit from it), you will return to
the regular menu. You can nest this way as many times as you have the
patience, or imagination.

DATA BASE MENU,Go To Data Base Menu,,MENU DATABASE.DAT -E

    The above command would call the Menu.bat file again, but this time it
would replace the data file name with DATABASE.DAT.

                                   Hints

    You should use the Menu.bat that comes with this program. The %1 %2 %3
etc. allows you to conveniently call the program using different options.
The program must run inside a batch file. Do not omit the "CD\" from the
beginning of the menu batch file. While the menu does not care where it is
run, you should make sure that it always runs in the same place. If you do
not, it will work, but it will pepper your drive with copies of Runit.bat.
This will waste space, and may cause confusion. You can run the program in
any directory, but the root is usually the best place. Be sure to set your
PATH in your Autoexec.bat to the directory in which you run your menu.

    PATH=C:\;C:\DOS         <- Sets your path to search both your
                             ROOT &  DOS Directories

    DO NOT try to exit the menu with a CTRL-BREAK. You will lock up your
system.

    If your command is a batch file, be sure to end your batch file with
"MENU", that will restart the menu, but it is better to precede the menu
command with a "CD\". This way you will not make your PATH command work so
hard.
    Any selection can have a password. You can put one on the selection to
go to the utility submenu for example (not on the submenu title line
itself). Please, do not use the passwords until you are comfortable with
the system. If you forget the password, you will have to reboot.
    If you want one batch file to call another, and then continue when the
other finishes, you must call the other batch file with the line
COMMAND /C BATCHNAME. This will invoke a secondary copy of the command
processor. Be aware that this exacts a penalty of as much as 40K while the
second batch file is in use. It is unlikely that you will ever want to use
this technique.
    Below is a sample Autoexec.bat

AUTOEXEC.BAT

DATE     <- You can use a Clock program if you have one.
TIME     <- You can use a Clock program if you have one.
PATH=C:\;C:\DOS             <- Or set to the path you like
MENU                        <- Call The Menu.bat file


    Take the time to experiment with this program. Be sure to run it with,
and without the Menu.bat file. Try to read the Runit.bat, and see how the
menu writes to it. If you do not have a ragged menu, try different ways to
move the cursor around. Remember that the END & HOME keys work.